Apache Wink : 5.8 Link Builder

The LinkBuilders interface enables access to two types of links builders, the SystemLinksBuilder and the SingleLinkBuilder. An instance of LinkBuilders is injected into a class field or method parameter using the @Context annotation.

Upon creation, the LinkBuilders automatically detects if the target method being invoked is a resource method or a sub-resource method. The "resource" and "subResource" properties of the builder are initialized accordingly. The link builder interfaces reside in the org.apache.wink.server.utils package.

Link Builders Overview

The JAX-RS specification defines the UriBuilder interface used to construct a URI from a template, but does not specify any mechanism that can automatically generate all resource links.
Apache Wink provides the SystemLinksBuilder for automatic generation of all the alternate links to a resource, one link per every supported media type. For example, this is useful for an application that produces Atom feeds to include in the feed all the alternate representations of the resource.

Apache Wink provides a mechanism for defining if the generated links should be absolute links or relative to a base URI. For example, links embedded in an Atom feed should be as short as possible in order to optimize the payload size.

The "alt" Query Parameter

Apache Wink supports the special query parameter "alt" that is used to override the value of the request Accept header. When the link builders generate a link that specifies the "type" attribute, then the "alt" query parameter is automatically added to the generated link. This is controlled by setting the wink.addAltParam key of the configuration properties file or by calling the LinksBuilder#addAltParam() method.

Reference
For more information on the Configuration Properties File refer to section 5.1 Registration and Configuration.

System Links Builder

The SystemLinksBuilder interface enables the generation of all, or a subset of, the system links to a resource or its sub-resources. The links are generated as absolute URIs or as relative to the base URI according to the SystemLinksBuilder state, request information or the application configuration.

Example

@Path("defects/{id}")
public class DefectResource {
@GET
@Produces("application/atom+xml")
public SyndEntry getAtom() {     ...   }
@GET
@Produces("application/json")
public JSONObject getJson() {    ...  }
}
@GET
@Produces("application/xml")
public Defect getXml(@Context LinkBuilders linkBuilders) {     SystemLinksBuilder builder = linkBuilders.systemLinksBuilder();     ListsystemLinks = builder.build(null);     ...   }
}

Explanation

The DefectResource#getXml() method is invoked when a GET request for application/xml is made to /defects/3. The Apache Wink runtime injects an instance of LinkBuilders to the linkBuilder parameter and a new instance of a SystemLinksBuilder is created by invoking the systemLinksBuilder() method.
The call to the build() method of the SystemLinksBuilder generates three alternate links to the DefectResource and the self link:

Single Link Builder

The SingleLinkBuilder interface enables the generation of a single link referencing a resource or a sub-resource, allowing the specification of the 'rel' and 'type' attributes of the generated link. The links are generated as absolute URIs or as relative to the base URI according to the SingleLinkBuilder state, request information or the application configuration.
Generating Absolute or Relative Links
The link builders generate absolute or relative links based on the following algorithm:

Reference
For more information on the Configuration Properties File refer to section 5.1 Registration and Configuration.